Hooks

Catalyst exposes two groups of hooks:

• route data hooks (useRouterData, useCurrentRouteData) and useRouterState from catalyst-core
• React Router hooks (useParams, useNavigate, useLocation, and the rest) from react-router, which Catalyst declares as a peer dependency
• native or universal app hooks from catalyst-core/hooks

Hooks Overview

Partial means behavior depends on browser support or fallback behavior in the web environment.

Route Hooks

useRouterData

The useRouterData hook provides access to the data for all matched routes.

Import

import { useRouterData } from "catalyst-core";

Return Value

Returns an object containing data for all active routes, keyed by route path.

Usage

import { useRouterData } from "catalyst-core";

const Layout = () => {
  const routerData = useRouterData();
  // { "/dashboard": { data, error, ... }, "/dashboard/settings": { data, error, ... } }
};

useCurrentRouteData

useCurrentRouteData provides access to the data resolved by serverFetcher or clientFetcher for the current route.

Import

import { useCurrentRouteData } from "catalyst-core";

Return Value

Requirements

This hook only works inside the RouterDataProvider tree. If the app is not wrapped in RouterDataProvider, the hook returns undefined.

Usage

import { useCurrentRouteData } from "catalyst-core";

const ProductPage = () => {
  const { data, error, isFetching, isFetched, refetch, clear } = useCurrentRouteData();

  return (
    <div>
      {isFetching && <Spinner />}
      {error && <Error message={error.message} />}
      {data && <ProductDetails product={data} />}
    </div>
  );
};

refetch

The refetch function can be used to re-run the clientFetcher for the current route.

const ProductList = () => {
  const { data, refetch } = useCurrentRouteData();
  const [page, setPage] = useState(1);

  useEffect(() => {
    refetch({ page });
  }, [page]);

  return <div>...</div>;
};

ProductList.clientFetcher = async ({ params }, { store }, { page = 1 }) => {
  const response = await fetch(`/api/products?page=${page}`);
  return response.json();
};

clear

The clear function can be used to remove the cached data for the current route.

const { clear } = useCurrentRouteData();

useEffect(() => {
  return () => clear();
}, []);

useRouterState

Added in 1.0.2. useRouterState returns the current router state through Catalyst's own router context instead of React Router's hooks. catalyst-core/webmcp uses it so that code loaded from a catalyst-core subpath reads the same router state as the app, even when the dev server resolves a separate copy of react-router for that subpath.

In application components, keep using useLocation, useParams and useNavigate from react-router. Reach for useRouterState in code that cannot import react-router itself.

Import

import { useRouterState } from "catalyst-core";

Return Value

{ location, params, navigate, matchedRoutes }: the current location, the params of the deepest matched route ({} when there are none), React Router's navigate function, and the matched route chain ([] when nothing matched).

It throws useRouterState must be used within a RouterDataProvider when called outside RouterDataProvider.

Universal App Hooks

Import universal hooks from catalyst-core/hooks:

import {
  useCamera,
  useFilePicker,
  useIntent,
  useGoogleSignIn,
  useCameraPermission,
  useNotificationPermission,
  useHapticFeedback,
  useNotification,
  useNetworkStatus,
  useDataProtection,
  useSafeArea,
  useDeviceInfo,
  useVideoStream,
  useNativeTransition,
} from "catalyst-core/hooks";

Native hooks fall into three categories. Which category a hook belongs to determines whether it has an execute function.

Single-action hooks

A hook that wraps exactly one native operation exposes that operation as execute, plus a domain-specific alias for the same function, plus state:

• execute — start the operation
• data — result payload, null until the operation completes
• loading — operation in progress
• error — standardized error object, null when there is no error
• progress — progress detail during the operation, where the platform reports it
• isWeb / isNative — runtime context
• clear — reset data and error
• clearError — reset error only

execute takes the operation's own arguments. It never takes an operation name.

useHapticFeedback also exposes one shortcut per feedback type (light, medium, heavy, success, warning, errorHaptic, selection, impact), each of which calls execute with that type.

Multi-action hooks

A hook that wraps several distinct native operations has no meaningful single action, so the named functions are the API. These hooks do not have an execute:

Multi-action hooks still expose the shared state keys (data, loading, error, isWeb, isNative, clear, clearError) where they apply.

useNotification is the one exception: it carries an execute key that aliases scheduleLocal, kept for backward compatibility. It is frozen but discouraged, and it is not the pattern to copy when writing or consuming multi-action hooks. See Aliases and Deprecations.

Read-only hooks

useNetworkStatus, useDeviceInfo, and useSafeArea report ambient device state. They have no action functions at all — they return state plus the runtime-context keys.

getDeviceInfo

Read device, screen, and app metadata from the native bridge. getDeviceInfo is exposed by WebBridge.init() and on window.WebBridge; it is not a React hook exported from catalyst-core/hooks.

Import

import WebBridge from "catalyst-core/WebBridge";

Returns

Resolves to an object with normalized device metadata.

Usage

const { getDeviceInfo } = WebBridge.init();

async function logDeviceInfo() {
  const deviceInfo = await getDeviceInfo();
  console.log(deviceInfo.platform, deviceInfo.model);
}

If the bridge is already initialized, you can also call window.WebBridge.getDeviceInfo(). On web, getDeviceInfo() resolves with browser and screen information instead of throwing.

useCamera

Access camera capture through the native bridge. The hook exposes a standardized stateful interface and camera-specific aliases.

Returns

Usage

takePhoto() returns undefined. It hands the request to the native shell and returns immediately — do not await it or read a return value. The captured photo arrives asynchronously on data, and a failure arrives on error. Read both from the hook, and react to the result in an effect if you need to run code when the capture lands.

function PhotoCapture() {
  const { takePhoto, loading, error, data, isNative } = useCamera();

  useEffect(() => {
    if (data) {
      console.log("Photo captured:", data.fileName);
    }
  }, [data]);

  return (
    <>
      <button onClick={() => takePhoto()} disabled={loading || !isNative}>
        Take Photo
      </button>
      {error && <p>{error.message}</p>}
      {data && <img src={data.fileSrc} alt="Captured" />}
    </>
  );
}

The same applies to execute, pickFile, openFile, and signIn: they dispatch to the native bridge and return undefined. useHapticFeedback's execute is the exception — when haptics are supported it returns a promise, resolving to the raw native status string on native and to a boolean on the web vibration fallback. When haptics are unsupported it records a FEATURE_UNSUPPORTED error and returns undefined rather than a promise, so guard on isSupported before awaiting.

useFilePicker

Open the native file picker and receive a normalized result payload.

Returns

Usage

function FileUpload() {
  const { pickFile, getAllFileObjects, loading } = useFilePicker();

  const handleSelectFile = async () => {
    pickFile({ mimeType: "application/pdf", multiple: true, maxFiles: 3 });
  };

  return <button onClick={handleSelectFile} disabled={loading}>Select File</button>;
}

useHapticFeedback

Trigger platform-specific haptic feedback with a standardized interface and semantic shortcuts.

Returns

Usage

function FeedbackButton() {
  const { medium } = useHapticFeedback();

  return <button onClick={() => medium()}>Submit</button>;
}

useIntent

Open a file or URL with an external native app.

Returns

Usage

function OpenInvoiceButton({ url }) {
  const { execute, loading } = useIntent();

  return (
    <button onClick={() => execute(url, "application/pdf")} disabled={loading}>
      Open Invoice
    </button>
  );
}

useCameraPermission

Check or request camera permission through the native bridge.

function CameraPermissionButton() {
  const { permission, isLoading } = useCameraPermission();

  return <button disabled={isLoading}>Camera permission: {permission || "checking"}</button>;
}

useNotificationPermission

Check or request notification permission before registering for push notifications.

function NotificationPermissionButton() {
  const { permission, isLoading } = useNotificationPermission();

  return <button disabled={isLoading}>Notification permission: {permission || "checking"}</button>;
}

useNotification

Manage local notifications and push registration from one hook.

Returns

Usage

function NotificationExample() {
  const { scheduleLocal, registerForPush, subscribeToTopic } = useNotification();

  return (
    <>
      <button onClick={() => scheduleLocal({ title: "Hey!", body: "You got a message" })}>
        Send Local Notification
      </button>
      <button onClick={() => { registerForPush(); subscribeToTopic("news"); }}>
        Enable Push Notifications
      </button>
    </>
  );
}

Requirements

Push-related notification features require WEBVIEW_CONFIG.notifications.enabled = true and the relevant Firebase platform files in the native projects.

useGoogleSignIn

Trigger Google sign-in through the native shell.

function GoogleLoginButton() {
  const { signIn, loading, error } = useGoogleSignIn();

  return <button onClick={signIn} disabled={loading}>Continue with Google</button>;
}

useNetworkStatus

Read connectivity state from the native bridge, with a browser fallback.

function ConnectivityBanner() {
  const { online, type } = useNetworkStatus();

  if (online) return null;
  return <div>Offline{type ? ` (${type})` : ""}</div>;
}

useDataProtection

Use native data protection and encryption helpers exposed through the bridge.

function ProtectedAction() {
  const { setScreenSecure, loading } = useDataProtection();

  return <button onClick={() => setScreenSecure(true)} disabled={loading}>Protect Screen</button>;
}

useSafeArea

Read safe-area insets in CSS pixels. Values are 0 when WEBVIEW_CONFIG.edgeToEdge.enabled is off, and on web and SSR.

function ScreenShell({ children }) {
  const safeArea = useSafeArea();

  return <main style={{ paddingTop: safeArea.top }}>{children}</main>;
}

useSafeArea has no error key. Insets always resolve to numbers, falling back to 0.

useDeviceInfo

Read device, screen, and app metadata as React state. This is the hook form of WebBridge.getDeviceInfo() documented above — the hook fetches on mount and re-renders when the result arrives, while getDeviceInfo() is a one-shot promise you call yourself.

Returns

The data payload carries the same fields as getDeviceInfo(): model, manufacturer, platform, screenWidth, screenHeight, screenDensity, and appInfo. On web, the fallback derives them from navigator.userAgent, screen, and window.devicePixelRatio, with manufacturer set to browser and platform set to web.

Usage

function DeviceBadge() {
  const { data, loading, error } = useDeviceInfo();

  if (loading) return <span>Detecting device…</span>;
  if (error) return <span>Device info unavailable: {error}</span>;

  return <span>{data.platform} · {data.model}</span>;
}

useVideoStream

Run a live camera preview through the native bridge, with QR detection and stream controls. This is a multi-action hook: it has no execute.

Returns

On native, the preview renders behind the WebView and viewfinderRef marks the cut-out region; mediaStream stays null. On the web fallback, mediaStream holds the getUserMedia stream to attach to a <video> element.

Usage

function QRScanner() {
  const { start, stop, isStreaming, viewfinderRef, error } = useVideoStream({
    onQRDetected: (value) => console.log("QR:", value),
  });

  return (
    <>
      <div ref={viewfinderRef} style={{ width: "100%", aspectRatio: "3/4" }} />
      <button onClick={() => (isStreaming ? stop() : start())}>
        {isStreaming ? "Stop" : "Scan"}
      </button>
      {error && <p>{error.message}</p>}
    </>
  );
}

useNativeTransition

Wrap useNavigate with native slide and fade transitions. On native, the shell snapshots the current screen, the route swaps behind the snapshot, and the overlay animates out. On web, the same state machine drives a CSS overlay. This is a multi-action hook: it has no execute.

Returns

navigate accepts the standard react-router NavigateOptions plus:

The same options can be passed once to the hook itself as defaults for every navigate call.

useNativeTransition has no error key. Transition failures self-heal: if the native start or commit fails, the hook logs, clears transitioning, and falls through to a plain navigation, so the user always lands on the destination route. A native-side safety timer force-fades the overlay if commit never arrives.

Usage

function ProductLink({ id }) {
  const { navigate, transitioning } = useNativeTransition({ type: "slide" });

  return (
    <button onClick={() => navigate(`/product/${id}`)} disabled={transitioning}>
      View Product
    </button>
  );
}

Aliases and Deprecations

Several hooks carry alias keys kept from earlier releases. Both names work and return the same value. The aliases are removed in 2.0 — write new code against the canonical key.

useNotification.execute and useNotification.schedule are aliases of scheduleLocal. They are frozen for compatibility but discouraged, and they are not the pattern to copy: multi-action hooks expose their named functions as the API and do not define execute. useNotification is the sole exception, for historical reasons.

Error shapes

error is a CatalystError from the framework-wide error registry everywhere, with the exception of two hooks. Native hook failures carry a RUNTIME-NATIVE-* code, a human-readable message, a category, a suggestedAction, a docUrl, and the originating platform error as cause. See the error handling guide for the registry itself.

useNativeTransition and useSafeArea are error-exempt: neither returns an error key at all. Transition failures self-heal into a plain navigation, and safe-area insets always resolve to numeric defaults.

useAI's shape — including its error handling — is owned by the catalyst-ai package and is outside this contract.

Hooks and bridge methods with the same name

requestHapticFeedback and requestCameraPermission exist both as functions exported from catalyst-core/hooks and as methods on WebBridge. They are not the same function: the defaults and return types differ.

requestHapticFeedback

requestCameraPermission

Prefer the catalyst-core/hooks exports in application code: they are SSR-safe and treat denial as a rejection. Use the WebBridge methods when you need the full result object or the config argument. The two surfaces are unified in 2.0.

useAI

Generate text through one of three providers, chosen with the provider option — the hook picks the underlying implementation for you:

Requires catalyst-ai to be installed in the app.

Import

import { useAI } from "catalyst-core/hooks";

Options

Returns

Usage

function Summarizer() {
  const { generate, output, streaming, loading, error } = useAI({
    provider: "openai",
    genConfig: { temperature: 0.3, maxTokens: 512 },
  });

  const handleSummarize = (document) => {
    generate({ messages: [{ role: "user", content: `Summarize: ${document}` }] });
  };

  return (
    <div>
      <button onClick={() => handleSummarize(doc)} disabled={loading}>Summarize</button>
      {streaming && <Spinner />}
      {error && <p>{error.message}</p>}
      {output && <p>{output}</p>}
    </div>
  );
}

genConfig

{
  temperature: number,        // 0-1
  maxTokens: number | null,
  topP: number,
  repetitionPenalty: number,  // native/web only
  noRepeatNgramSize: number,  // native/web only
  stream: boolean,
}

stream: true uses the SSE path; stream: false uses a single-JSON-response path. Cloud and native both expose real stream/generate HTTP routes for this. The transformers provider ignores genConfig.stream — the Worker always runs the full generation and streams tokens back internally via postMessage.

Stateful Sessions

Pass sessionMode: "stateful" to carry conversation context across calls. The mechanism is different for each provider, since each has a different notion of "session":

• Cloud — the client sends conversationId in the request body; the server translates it into the underlying provider's own continuation token (previous_response_id for OpenAI, previous_interaction_id for Gemini) and returns a fresh conversationId with each response.
• Native — the client sends conversationId to the Ktor route; the Android engine reuses the same LiteRT-LM Conversation object when the incoming id matches its current one, otherwise starts a new one. reset() also tells the native bridge to drop that object.
• Web (experimental) — there is no engine-side session at all. "Stateful" here means the hook accumulates prior { role, content } turns client-side and replays the full history into every generate() call — real chat, not KV-cache reuse. conversationId is just a locally-generated id for the UI to key off; it carries no meaning beyond the hook instance.

reset() clears output, conversation history, and conversationId in all three cases. sessionMode: "stateless" (the default) makes every generate() call independent.

Metrics

metrics (after a call) and getSessionMetrics() (aggregated across the session) differ by provider:

• Cloud includes cost, cachedTokens, cacheSavings, and a byProvider breakdown, alongside ttftMs/tps/totalTokens.
• Native and web have no billing, so their metrics are the leaner { device, ttftMs, tps, totalTokens, genMs } (web additionally reports dtype, loadMs, and downloadBytes for the model download).

Call resetSessionMetrics() to clear accumulated history without ending the current conversation.

Attachment Components

Pass attachmentComponents to have the model return structured, renderable output instead of plain text:

useAI({
  attachmentComponents: {
    InfoCard: { attrs: { title: "string", type: "info|warning|success" }, hint: "1 sentence callout" },
  },
});

The model is instructed (via an injected system prompt) to wrap relevant output in {% ComponentName attr='val' %}body{% /ComponentName %} tags. output contains the raw tagged text — render it with renderOutput(output, streaming) from utils/ai.js, or the AttachmentRenderer component. Each key must correspond to a registered React component.

Requirements

Requires catalyst-ai to be installed (npm install catalyst-ai). Without it, useAI logs an error and returns an inert hook (all booleans false, generate/cancel/reset are no-ops).

useAI's return shape is owned by the catalyst-ai package and sits outside the native hook contract described on this page. It does not follow the single-action or multi-action categories, and the alias and error-shape rules above do not apply to it.